package ca.usherbrooke.domus.sipnmove2.model.call;

import java.util.Map;

import ca.usherbrooke.domus.sipnmove2.model.communication.Communication;

/**
 * A call like a phone call
 * 
 * Calls are typically created by a user agent when incoming call events are 
 * processed or when a new call is asked to a user agent.
 * 
 * This is the element of communication that memorizes the state of the 
 * communication and that handle information about a specific communication 
 * (peer information, communication type, etc.)
 */
public interface Call {

	/**
	 * Accept the call
	 */
	public void accept();

	/**
	 * Confirm the call
	 */
	public void confirm();

	/**
	 * Hang up the call
	 */
	public void hangUp();

	/**
	 * Initiate the call
	 */
	public void initiate();

	/**
	 * Make the call ringing
	 */
	public void ring();

	/**
	 * Terminate the call
	 */
	public void terminate();

	/**
	 * Define the call state
	 * @param callState The new call state of the call
	 */
	public void setState(CallState callState);

	/**
	 * Return the current state of the call
	 * @return the current state of the call
	 */
	public CallState getState();
	
	/**
	 * Add a call observer
	 * @param callObserver Call observer that will be notified of a call state changed
	 */
	public void addCallObserver(CallObserver callObserver);

	/**
	 * Return the parameters of the call
	 * @return the parameters
	 */
	public Map<String, Object> getParameters();

	/**
	 * Define the parameters of the call
	 * @param parameters the parameters to set
	 */
	public void setParameters(Map<String, Object> parameters);

	/**
	 * Return the communication associated to this call
	 * @return The communication associated to this call
	 */
	public Communication getCommunication();

	/**
	 * Define the communication associated to this call
	 * @param communication Communication to be assigned to this call
	 */
	public void setCommunication(Communication communication);
}
